fix(ui): resolve root-relative README markdown links to repo blob URLs by BittuBarnwal7479 · Pull Request #2929 · npmx-dev/npmx.dev

BittuBarnwal7479 · 2026-06-17T12:24:45Z

🔗 Linked issue

🧭 Context

Steps to Reproduce

Open https://npmx.dev/package/astro
Find a README link that points to /CONTRIBUTING.md
Click the link

Recording.2026-06-17.174239.mp4

📚 Description

On package readme.ts page, root-relative markdown links such as /CONTRIBUTING.md are resolved as local npmx routes instead of repository files.

vercel · 2026-06-17T12:24:51Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
npmx.dev	Ready	Preview, Comment	Jun 17, 2026 9:40pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs.npmx.dev	Ignored	Preview	Jun 17, 2026 9:40pm
npmx-lunaria	Ignored		Jun 17, 2026 9:40pm

coderabbitai · 2026-06-17T12:24:59Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d54a9330-8917-4102-9a57-80c407e4e5f0

📥 Commits

Reviewing files that changed from the base of the PR and between a0b738c and 03ae304.

📒 Files selected for processing (2)

server/utils/readme.ts
test/unit/server/utils/readme.spec.ts

🚧 Files skipped from review as they are similar to previous changes (2)

test/unit/server/utils/readme.spec.ts
server/utils/readme.ts

📝 Walkthrough

Summary by CodeRabbit

Style
- Improved the “Badge Style” selector styling for clearer light/dark text and tidier option formatting.
Bug Fixes
- Enhanced README link URL resolution, including correct handling of root-relative paths, choosing blob vs raw URLs for markdown, and improved behaviour for npm-style redirect links.
Tests
- Expanded unit coverage for markdown file URL resolution with repository context, including raw HTML link cases and ensuring protocol-relative URLs remain unchanged.

Walkthrough

server/utils/readme.ts gains a LOCAL_NPMX_REDIRECT_PREFIX constant and toLocalNpmxRedirect() helper to mark locally-resolved redirects. resolveUrl() now strips this prefix immediately, computes markdown detection earlier, and conditionally rewrites root-relative paths to repository blob or raw URLs. Redirectable npmjs URLs are wrapped with the prefix instead of returning the pathname directly. 72 lines of unit tests cover all new branches. BadgeGeneratorParameters.vue receives minor Tailwind dark-mode class additions on the Badge Style dropdown.

Changes

Root-relative URL resolution fix

Layer / File(s)	Summary
Local redirect prefix constant and toLocalNpmxRedirect() wrapper `server/utils/readme.ts`	Introduces `LOCAL_NPMX_REDIRECT_PREFIX` constant and `toLocalNpmxRedirect(path)` helper to wrap locally-resolved paths with the `$npmx-local:` prefix for deferred handling by `resolveUrl()`.
resolveUrl() prefix stripping and URL rewriting refactor `server/utils/readme.ts`	Updates `resolveUrl()` to immediately strip `LOCAL_NPMX_REDIRECT_PREFIX`, compute `isMarkdownFile` earlier, conditionally rewrite absolute-path URLs based on `repoInfo` presence and markdown status (using `blobBaseUrl` for `.md`, `rawBaseUrl` for non-markdown), return npmjs redirects via `toLocalNpmxRedirect()`, and remove the now-duplicate `isMarkdownFile` computation.
Unit tests for new URL resolution branches `test/unit/server/utils/readme.spec.ts`	Adds "with repository info" cases: root-relative `.md` links (including raw HTML `<a>` tags) resolve to the repository blob URL; root-relative non-`.md` links resolve to the raw URL; `/package/...` paths are resolved to repository raw URL; `www.npmjs.com/package/...` redirects remain local as `/package/...`; route-root paths (`/package`, `/org`) stay local; protocol-relative URLs remain unchanged.

Badge Style dropdown dark-mode styling

Layer / File(s)	Summary
Badge Style select Tailwind classes `docs/app/components/BadgeGeneratorParameters.vue`	`<select>` element gains explicit text colour classes for light and dark themes; each `<option>` element gains `dark:bg-gray-900` with reformatted markup.

Possibly related issues

root-relative markdown links resolve to npmx host #2928: The changes in this PR directly address this issue by modifying resolveUrl() in server/utils/readme.ts to detect and handle local NPMX paths using the new prefix marking system, correctly rewriting root-relative markdown links (for example /CONTRIBUTING.md) to repository blob URLs rather than treating them as npmx host routes.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title accurately reflects the main change: fixing resolution of root-relative markdown links in README files to point to repository blob URLs rather than local npmx routes.
Description check	✅ Passed	The description is directly related to the changeset, providing context about the bug (root-relative markdown links being incorrectly resolved), the steps to reproduce it, and the intended fix.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

codecov · 2026-06-17T12:26:45Z

Codecov Report

❌ Patch coverage is 63.63636% with 4 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
server/utils/readme.ts	63.63%	1 Missing and 3 partials ⚠️

📢 Thoughts on this report? Let us know!

coderabbitai · 2026-06-17T12:31:18Z

Caution

Review failed

An error occurred during the review process. Please try again later.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

gameroman · 2026-06-17T18:13:27Z

+      const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)
+
+      expect(result.html).toContain('href="/package/test-pkg"')
+    })


Is there a reason why we want this behaviour for non-markdown links?

Why not something similar to what is done for this?

npmx.dev/test/unit/server/utils/readme.spec.ts

Lines 219 to 227 in 46e7c59

it('resolves non-.md files to raw URL (not blob)', async () => {

const repoInfo = createRepoInfo()

const markdown = `[Image](./assets/logo.png)`

const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)

expect(result.html).toContain(

'href="https://raw.githubusercontent.com/test-owner/test-repo/HEAD/assets/logo.png"',

)

})

Good catch. I updated this to resolve root-relative non-markdown links via rawBaseUrl, consistent with existing relative-link handling. Markdown files still resolve via blobBaseUrl.

Local npmx routes (/package, /org, /search, etc.) are preserved separately, and I added regression tests covering both behaviors.

Is there a reason / place where preserving Local npmx routes would be useful instead of them resolving to rawBaseUrl too?

yes. the main case is npmjs links that the README renderer intentionally converts to local npmx routes. For example, https://www.npmjs.com/package/test-pkg becomes /package/test-pkg.

If we treated every root-relative path as a repo file, that converted route would incorrectly become rawBaseUrl/package/test-pkg.

So the updated logic preserves known npmx routes separately, while root-relative repo files like /CONTRIBUTING.md and /assets/logo.png resolve to blobBaseUrl / rawBaseUrl.

Hmm, is there no way to differentiate a /package that was because of https://www.npmjs.com/package/test-pkg from a /package that someone wrote in their readme?

good point. i will update this to preserve npmjs-originated links via an internal marker rather than path matching. README-authored root-relative paths now resolve normally against the repository. Added regression tests for both cases.

coderabbitai

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

server/utils/readme.ts (1)
352-358: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Keep protocol-relative URLs out of the root-relative rewrite.

//cdn.example.com/file.css also satisfies url.startsWith('/'), so with repository info it becomes https://raw.githubusercontent.com/.../HEAD//cdn.example.com/file.css instead of staying external. The later protocol-relative handling never gets a chance to run.
Proposed fix
-  if (url.startsWith('/')) {
+  if (url.startsWith('/') && !url.startsWith('//')) {
     if (!repoInfo?.rawBaseUrl) {
       return url
     }
 
     const baseUrl = isMarkdownFile ? repoInfo.blobBaseUrl : repoInfo.rawBaseUrl
     return `${baseUrl}${url}`
   }
Please add a regression case such as [CDN](//cdn.example.com/file.css) with repoInfo and assert the href remains protocol-relative.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@server/utils/readme.ts` around lines 352 - 358, The root-relative URL check
at the beginning of the conditional block (url.startsWith('/')) is incorrectly
matching protocol-relative URLs that start with //, causing them to be rewritten
as repository URLs instead of remaining external. Add an additional condition to
explicitly exclude protocol-relative URLs (those starting with //) before
processing the root-relative URL case in the repoInfo block. Additionally, add a
regression test case that verifies a markdown link with a protocol-relative URL
like [CDN](//cdn.example.com/file.css) correctly preserves the protocol-relative
href when repoInfo is present.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@server/utils/readme.ts`:
- Around line 352-358: The root-relative URL check at the beginning of the
conditional block (url.startsWith('/')) is incorrectly matching
protocol-relative URLs that start with //, causing them to be rewritten as
repository URLs instead of remaining external. Add an additional condition to
explicitly exclude protocol-relative URLs (those starting with //) before
processing the root-relative URL case in the repoInfo block. Additionally, add a
regression test case that verifies a markdown link with a protocol-relative URL
like [CDN](//cdn.example.com/file.css) correctly preserves the protocol-relative
href when repoInfo is present.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e84a9795-dd1d-41b7-b64c-33fc7a943e87

📥 Commits

Reviewing files that changed from the base of the PR and between 5e7897b and a0b738c.

📒 Files selected for processing (2)

server/utils/readme.ts
test/unit/server/utils/readme.spec.ts

BittuBarnwal7479 · 2026-06-17T21:42:48Z

@CodeRabbit review again.

coderabbitai · 2026-06-17T21:43:00Z

@BittuBarnwal7479 Sure! I'll kick off a new review of the PR right away.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Your Name added 2 commits June 15, 2026 05:35

fix(docs): respect dark theme in badge style dropdown

be3fd49

fix(readme): handle root-relative markdown file links

8c7bbae

vercel Bot deployed to Preview – npmx.dev June 17, 2026 12:27 View deployment

BittuBarnwal7479 changed the title ~~Resolve root-relative README markdown links to repo blob URLs~~ fix(ui): resolve root-relative README markdown links to repo blob URLs Jun 17, 2026

gameroman reviewed Jun 17, 2026

View reviewed changes

refactor: clean up root-relative link handling

5e7897b

vercel Bot deployed to Preview – npmx.dev June 17, 2026 21:03 View deployment

fix: preserve npmjs rewritten routes without path matching

a0b738c

vercel Bot deployed to Preview – npmx.dev June 17, 2026 21:31 View deployment

coderabbitai Bot reviewed Jun 17, 2026

View reviewed changes

fix: apply coderabbit suggestion

03ae304

vercel Bot deployed to Preview – npmx.dev June 17, 2026 21:40 View deployment

	it('resolves non-.md files to raw URL (not blob)', async () => {
	const repoInfo = createRepoInfo()
	const markdown = `[Image](./assets/logo.png)`
	const result = await renderReadmeHtml(markdown, 'test-pkg', repoInfo)

	expect(result.html).toContain(
	'href="https://raw.githubusercontent.com/test-owner/test-repo/HEAD/assets/logo.png"',
	)
	})

Uh oh!

Conversation

BittuBarnwal7479 commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Linked issue

🧭 Context

📚 Description

Uh oh!

vercel Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Walkthrough

Changes

Possibly related issues

Uh oh!

codecov Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

coderabbitai Bot commented Jun 17, 2026

Review failed

Uh oh!

gameroman Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

BittuBarnwal7479 Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

gameroman Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

BittuBarnwal7479 Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gameroman Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

BittuBarnwal7479 Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

BittuBarnwal7479 commented Jun 17, 2026

Uh oh!

coderabbitai Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BittuBarnwal7479 commented Jun 17, 2026 •

edited

Loading

vercel Bot commented Jun 17, 2026 •

edited

Loading

coderabbitai Bot commented Jun 17, 2026 •

edited

Loading

codecov Bot commented Jun 17, 2026 •

edited

Loading

BittuBarnwal7479 Jun 17, 2026 •

edited

Loading

coderabbitai Bot commented Jun 17, 2026 •

edited

Loading